home *** CD-ROM | disk | FTP | other *** search
<TITLE>WebSite 1.0 Self-Test</TITLE> <H1><IMG SRC="../images/website.gif" ALT="WebSite" WIDTH=216 HEIGHT=72> Self-Test</H1> <p> This document exercises (and demonstrates) many of the capabilities of your WebSite server and your browser. Please take the time to work through each feature. Don't worry if the more esoteric features don't seem to make sense; you'll know the reasons for them soon after you start using the server for real things. <p> For additional information on these features, check out <a href=http://website.ora.com/>WebSite Central</a>, which has updates, Q/A, add-ons, betas, and more. <p> If you are having difficulties, please consult the <a href=../trouble.html>troubleshooting tips</a>. <HR> <H2><IMG SRC = "../images/rfinger.gif" ALT="*" WIDTH=32 HEIGHT=32> Self-Test Checklist</H2> <P>Here's a checklist you can use to verify your setup: <UL> <LI>You have read <A HREF="../trouble.html">Troubleshooting Tips</A>. <LI>You are using a browser that supports forms, image maps, and basic authentication (most do) <LI>You have enabled automatic fetching of inline images <LI>Your browser is configured to accept and view GIF and basic sound <LI>You have a GIF viewer and sound player installed and tested with your browser <LI>The WebSite server is running <LI>You are reading this document from the server (not as a local file) <LI>For Windows 95, you have added the <CODE>CommandEnvSize=8192</CODE> line to the <CODE>[NonWindowsApp]</CODE> section of SYSTEM.INI and rebooted. </UL> If you know or are unsure that your setup needs some of these features, consult the <a href=http://gnn.com/gnn/mosaic/windows/winhot.html>Windows Mosaic Hotlist</a> for suggestions. <HR> <H2>Introduction</H2> Your new server has the capabilities you need to produce powerful yet easy to use presentations and services. It supports the following main features: <UL> <LI>Information Retrieval: <UL> <LI><A HREF = "#basic">Basic document retrieval</A> (hypertext, plain text, images, etc.) <LI><A HREF = "#treenav">Directory tree navigation & file retrieval</A> (fancy alternative to FTP site) <LI><A HREF = "#imagemap">Actions based on clicking "hot-regions" in an image</A> (use an image as a "switchboard") <LI><A HREF = "#urlfix">Automatic URL-Fixup</A> (vital, but esoteric) </UL> <LI>Using an external program (CGI) to generate results: <UL> <LI><A HREF = "#pizza"><b>Sample Order-Entry Application</b></A> <LI><A HREF = "#forms">Processing fill-in forms</A> <LI><A HREF = "#docquery">Document-based queries</A> </UL> <LI>WebSite's Three CGI Interfaces: <UL> <LI><A HREF = "#wincgi">Using Visual Basic or other Windows programs</A> <LI><A HREF = "#shellcgi">Using a Win32 or POSIX shell</A> (e.g. <code>perl</code> or <code>sh,</code> Unix-compatible) <LI><A HREF = "#doscgi">Using the DOS command interpreter and/or DOS applications</A> </UL> <LI>Security Features: <UL> <LI><A HREF="#access">Overview</A> <LI><A HREF = "#useracc">Username/Password per-directory access control</A> <LI><A HREF = "#filtacc">IP address and host name filtering</A> </UL> <LI>Miscellaneous: <UL> <LI><A HREF = "#stats">Viewing the server's statistics</A> <LI><A HREF = "#admin">Server administration with your browser</A> </UL> </UL> <HR> <H2><A NAME = "basic">Basic Document Retrieval</A></H2> This is the most basic, yet most often used, function that your server provides. When the user clicks on a hot-spot, the browser sends a request to the server and the server returns the requested document.<P> Here is a <A HREF = "basic.txt">plain text document</A><BR> Here is a <A HREF = "basic.html">hypertext document</A><BR> Here is a <A HREF = "images/rbd.gif">GIF image</A> (the server author)<BR> Here is an <A HREF = "ring.au">audio clip</A><BR> You can also use an image <A HREF = "basic.html"> <IMG SRC = "../images/question.gif" WIDTH=32 HEIGHT=32></A> as a hot-spot. <HR> <H2><A NAME = "treenav">Directory Tree Navigation</A></H2> This feature permits the server to display directories on your PC and let Web users browse and retrieve files. In addition, as server administrator, you can create text descriptions for files to assist your users in identifying and locating files. You can look at this feature as a "fancy FTP". It does <I>not</I> use the FTP protocol; it uses the Web's own HTTP for file transfers. <P>For this demo, I have created a small <A HREF = "demotree/">directory tree</A> with some useless documents in it. Have a look and you'll get the idea. Clicking on the Parent Directory entry at the top of the demo tree will take you back to this demo document. Can you figure out how that happens? <HR> <H2><A NAME = "imagemap">Image Maps</A></H2> The server has the built-in ability to process clicks within an inline image and perform actions based on the <I>location</I> of the click. This is called "image map" support. With it, for example, you can create a graphical map of a complex set of Web pages and let your users navigate visually. Obviously, many other clever things can be done with image maps.<P> Here is an inline GIF image. Click in it and see what happens.<P> <a href=/~imagemap/32demo> <img src="images/imapdemo.gif" ISMAP WIDTH=300 HEIGHT=100></a><P> In contrast to all other known Web servers, this server does not require running an external program to handle image map requests. <B>The support is built into the server</B>. This makes the server very efficient at handling image mapping.<P> <h3>The Two Ways to do Image Maps</H3> Actually, there are two ways to make image maps. The traditional way is to use the <code>ISMAP</code> element within an image tag, then enclose it with a link to the image mapper. The above example uses this method. The HTML used above is: <PRE><A HREF = "/~imagemap/32demo"> <IMG SRC = "images/imapdemo.gif" ISMAP> </A></PRE> The <code>~imagemap</code> part of the URL accesses the server's special built-in image mapper, and the <code>32demo</code> in the URL is the name of the map to be used to decide what to do depending on where you clicked. <P><A NAME="imagemap2"></A> Another way to make an image map uses an obscure but useful feature of HTML forms. Create an input field of type <code>IMAGE</code> within a form whose execution target is the image mapper. Forms can use either the <code>GET</code> or <code>POST</code> method, and the server's internal image mapper can handle either. Examples of each variation, along with the actual HTML used, appear below. <PRE><FORM METHOD="<B>POST</B>" ACTION="/~imagemap/32demo"> <INPUT TYPE=IMAGE SRC="/wsdocs/32demo/images/imapdemo.gif"> </FORM></PRE> <FORM METHOD="POST" ACTION="/~imagemap/32demo"> <INPUT TYPE=IMAGE SRC="/wsdocs/32demo/images/imapdemo.gif" WIDTH=300 HEIGHT=100> </FORM> <PRE><FORM METHOD="<B>GET</B>" ACTION="/~imagemap/32demo"> <INPUT TYPE=IMAGE SRC="/wsdocs/32demo/images/imapdemo.gif"> </FORM></PRE> <FORM METHOD="GET" ACTION="/~imagemap/32demo"> <INPUT TYPE=IMAGE SRC="/wsdocs/32demo/images/imapdemo.gif" WIDTH=300 HEIGHT=100> </FORM> <HR> <A NAME="urlfix"><H2>Automatic URL-Fixup</H2></H2> This section checks out a vital feature of your server, its ability to fix up directory URLs that don't have a trailing slash. Don't bother to try to understand why this is needed for now. Look at the URL that is displayed at the top of your browser. It ends either with <code>index.html </code> or with a trailing slash. Click the link below. If this document is successfully redisplayed, the feature is working. If you get an error, your hostname is not configured correctly. Use the WebSite Server Setup applet to correct your hostname and then try this test again. Try it now: <PRE><A HREF="http://localhost/wsdocs/32demo">http://localhost/wsdocs/32demo</A> <-- missing trailing slash</PRE> Now look at the displayed current URL. It should have a trailing slash on it, and it also has the port number after the host name. <HR> <A NAME="pizza"><H2>Sample Order-Entry Application</H2></A> This example uses a form to provide an <A HREF="/cgi-win/pizza.exe">order-entry service</A>. The external forms-processing program <CODE>pizza.exe</CODE> is a Visual Basic application, compiled into an executable. The same program generates the form as well as processing its results. Note that the form has the current time on it. <P><B>NOTE:</B> This example is an <i>excellent</i> reference implementation for forms applications. If you are interested in developing forms-based applications, please take the time to read the VB code in <CODE>pizza.bas</CODE>. <HR> <H2><A NAME="forms">Forms Processing</A></H2> Forms must be processed by a CGI program. One of the difficulties encountered by most people who develop programs for their forms is that of decoding the form data. The browser sends this data in a special form called "URL-encoded". If you use the <A HREF="windows-cgi.html">Windows CGI</A> interface, the server will decode all forms information for you. Furthermore, the Visual Basic template application contains a module that handles reading the decoded form information into VB globals, then calls your module to do the actual processing. This is a major time (and frustration) saver, and is a feature available only on this server. <h3>Sample search form</h3> Here is a simple form that uses a VB CGI program. Fill in the field and select an option, then click the "Search" button. The demo back end simply reports what would ordinarily be submitted to the database search engine:<P> The "search on" field supports multiple selections (may not be supported by your browser). Try it and see how the server handles decoding it. Netscape lets you select multiple items with the shift and control keys, per standard Windows conventions. <HR> <FORM METHOD="POST" ACTION="/cgi-win/cgitest.exe/Form"> Search on (multiple)<SELECT NAME="LookFor" MULTIPLE> <OPTION SELECTED>Name <OPTION>Title <OPTION>Department <OPTION>Location <OPTION>Employee ID </SELECT><P> which <SELECT NAME="How"> <OPTION SELECTED>starts with <OPTION>contains <OPTION>is exactly <OPTION>sounds like </SELECT><P> the following: <INPUT TYPE="text" NAME="Match-pattern"><P> <INPUT TYPE="checkbox" NAME="Use-Case" VALUE="Yes">Case-sensitive<P> <INPUT TYPE="submit" VALUE="Search"> </FORM> <HR> <H2><A NAME = "docquery">Document Based Queries</A></H2> Most browsers have a feature that permits a hypertext document to trigger display of a "query field". When the user enters something into the query field the browser sends a special request to the server. You can set up your server to offer query documents and process queries by using the CGI program facilities. In this way, you can offer services that provide searching databases, etc.<P> Here are links to the <A HREF="/cgi-dos/demoindx.cmd">Windows NT</A> and <A HREF="/cgi-dos/demoindx.bat">Windows 95</A> versions. They differ because of differences in the capabilities and syntax of the NT and '95 DOS command processors. These demos use the server's <A HREF="#doscgi">DOS CGI support</a>. <HR> <A NAME = "wincgi"><H2>Windows CGI Interface</H2></A> The server supports a variant of CGI that is well suited to the Windows environment. In addition, the server comes with a template Visual Basic 3.0 kit that allows you to develop sophisticated CGI programs quickly. Since VB can access a wide variety of information sources such as Access and SQL Server databases, your flexibility is almost unlimited. It is this capability that sets the Windows Web Server apart from other Windows NT- and Unix-based Web servers.<P> The sample is a test program that produces various reports as to the CGI environment it gets from the server. The reports are in HTML format. The sources to this test program are in the /cgi-src directory, plus a "usage" page in the server document root. The usage page is returned if no test selector is specified (as "extra path" info). <P> The URL to get the usage page is: <PRE><A HREF = "/cgi-win/cgitest.exe">/cgi-win/cgitest.exe</A></PRE> Try it now. Don't worry if you don't understand everything you see. Just understand that when you use this link, you are executing a compiled Visual Basic program. For more information, see the <A HREF = "windows-cgi.html">Windows CGI documentation</A>. <HR> <A NAME="shellcgi"><H2>Standard CGI Interface</H2></A> Web pioneers have developed many CGI applications using Unix shell scripts and the <code>perl</code> language. Windows NT has a POSIX subsystem that can be used from the server to execute Unix applications as CGI programs. The Windows NT Resource Kit contains a basic set of Unix command utilities, including an <i>excellent</i> Korn Shell clone. In addition, there is a Windows NT port of <code>perl</code> available at <A HREF="ftp://ftp.intergraph.com/pub/win32/perl/"> ftp://ftp.intergraph.com/pub/win32/perl/</a>.<P> The Pure CGI interface provided by the server on NT is virtually identical to that provided by Unix-based servers. Therefore, you can use existing CGI applications written in shell and perl, as long as you have the other utilities needed by those scripts. You can also use 32-bit Windows applications and/or associated documents as long as the app is written for the pure CGI/1.1 interface.<P> <IMG SRC="../images/exclam.gif" WIDTH=16 HEIGHT=32> <B>WARNING:</B> Windows 95 cannot pass environment variables to DOS/Console programs, so you must use the DOS CGI interface for this sort of thing. It's tricky. If you have a Windows executable that can handle the pure CGI interface, and your version of Windows 95 properly passes environment variables, you could use such a program with pure CGI on Windows 95. <H3>Associations</H3> As shipped, the server uses the "associations" you set up to determine the correct shell to use for a script or document. In order for the demos below to work, you must associate files of type <CODE>.sh</CODE> with the <CODE>SH.EXE</CODE> Korn Shell from the resource kit, and <CODE>.pl</CODE> with the NT <CODE>perl</CODE> interpreter. <I> You must use fully qualified pathnames for these associations</I>. Do not rely on the "path". <H3>Korn Shell Script (NT Only)</H3> (<I>demo requires</I> <code>sh.exe</code> <I>from the NT Resource Kit</I>)<P> Here is a simple Korn shell script that <A HREF="/cgi-shl/ARGS.SH/a/b/c?1+2+3">sends back the names and values of some CGI environment variables</a>. Note that the pathnames in system-generated and server-generated variables are in POSIX format. The server automatically determines whether the shell is a Win32 or POSIX type and makes the appropriate conversion on all physical pathnames it sends to the CGI program. <H3><CODE>perl</CODE> Script (NT Only)</H3> (<I>demo requires NT</I> <CODE>perl</CODE> <I>interpreter</I>)<P> Here is a <A HREF="/cgi-shl/args.pl/a/b/c?1+2+3">small <CODE>perl</CODE> script</A> which (of course) sends back the names and values of some CGI environment variables. Note that the pathnames are in the native Win32 syntax. The server knows that the <CODE>perl</CODE> interpreter is a native Win32 app, not a POSIX type. <HR> <A NAME="doscgi"><H2>DOS CGI Interface</H2></A> The server can use batch files and programs that run in the DOS shell environment of Windows NT and Windows 95. The command processors are very limited, so you should use this interface for simple applications only. Actually, we strongly recommend that you take the time to learn Visual Basic and use the <A HREF="#wincgi">Windows interface</A> for your CGI work.<P> The DOS command processors for Windows NT and Windows 95 are quite different in their capabilities, therefore we need different batch files for each. By convention we use <CODE>.CMD</CODE> for Windows NT batch files, and <CODE>.BAT</CODE> for Windows 95. Here is a simple example that uses a DOS batch file to send back the name and version of your browser. There is a version for <A HREF="/cgi-dos/browser.cmd">Windows NT</A> and one for <A HREF="/cgi-dos/browser.bat">Windows 95</A>.<P> This batch file <A HREF="/cgi-dos/args.cmd/a/b/c?1+2+3">(NT version)</A> <A HREF="/cgi-dos/args.bat/a/b/c?1+2+3">(Win95 version)</A> generates a report of some info it got from the server. This info is passed via environment variables, according to the Common Gateway Interface 1.2 (CGI/1.2).<P> <HR> <H2><A NAME = "access">Access Control</A></H2> Your server has the ability to provide fine-grain control of access to documents and scripts. Access can be controlled by user, by group, by client host (domain) name, client IP address, or any combination of these.<P> <blockquote><IMG SRC = "../images/note.gif" WIDTH=32 HEIGHT=32> Browsers remember the username and password you enter. If you type in the correct username and password, you will be permitted to access the document, and you won't be able to try an incorrect combination until you exit and restart your browser. I suggest you start with the wrong username and/or password. Then when you try again, you'll get a "access failure" alert. Choose the try again button and you can type in another (correct) username and password.</blockquote> <A NAME="useracc"><h3>User and Group Access Control</H3></A> WebSite can provide per-directory protection to users and/or groups of users. Access control is <i>not</i> related to the Windows NT security system. <I>There is no need to give an NT account to a Web user!</I> This security is available under Windows 95, another reason WebSite has its own security system (Windows 95 has no built-in object-level access control). <P><B>Usernames and passwords are case-sensitive</B> <P><A HREF="AuthExamples/bypasswd/demodoc.html">This document</A> can be accessed only by user <I>Dougherty</I> with password <I>balloon</I>. <A HREF="AuthExamples/bypwmult/demodoc.html">This document</A> can be accessed either by user <I>Weber</I> with password <I>Jay</I>, or by user <I>Denny</I> with password <I>Bob</I>. <P>The server also permits access by groups of users, and the Web Server Setup utility permits easy manipulation of group membership.All users are automatically included in the group "Users". Therefore, you can allow access to any valid user by allowing access by the group "Users".<A HREF="AuthExamples/bygroup/demodoc.html">This document</A> can be accessed by any user.<P> <A NAME="filtacc"> <h3>Hostname and IP Address Filtering</h3></a>You can also control access by host name or IP addresses. For example, <A HREF="AuthExamples/bydomain/demodoc.html">this document</A> can be accessed only by hosts within the IP address range 198.211.*.*, and <A HREF="AuthExamples/bydomexc/demodoc.html"> this one </A> can be accessed by any hosts except those in the IP address range 198.211.*.*. Although it is possible to filter by host name, we don't recommend it because it requires that the server do a DNS reverse lookup (to convert the IP address to the host name) on every request. This will noticably degrade the response time of the server on all requests.<HR> <A NAME = "stats"><H2>Statistics Reports</H2></A> The server will send a <A HREF="/~stats">statistics report</A> by sending it a URL of <CODE>/~stats</CODE>. Try it now. If you are connected to the net, you can see the <A HREF="http://website.ora.com/~stats">WebSite Central server's statistics</A>. <HR> <A NAME = "admin"><H2>Server Administration</H2></A> You may have noticed that the server responds to certain URLs that start with the tilde character in special ways. You have seen <code>~imagemap</code> and <code>~stats</code> so far. As you may have guessed, there are others. The two just mentioned are "safe", i.e., they don't "do" anything except retrieve data.<P> The server supports a few additional special URLs that can be used to perform some administrative tasks. These functions "do" something, therefore in keeping with the HTTP protocol, they must be issued with the <code>POST</code> method. Forms can issue <code>POST</code>s, and they can have buttons, so you can make up an administration form that contains the special function buttons you want.<P> As shipped, the server is set up to protect these special URLs as well, since they can affect the operation of the server. In order to successfully use these functions, you must first authenticate yourself as a member of the <code>Administrators</code> group. If you haven't yet added yourself as a user in the WebServer realm, do so now. Then add yourself to the Administrators group.<P> If successful, these special functions return the HTTP <code>204 No Response</code> result, so the browser stays on the current page. <P> Now that you know the essentials, here are the buttons: <FORM METHOD="POST" ACTION="/~zero-ctrs"> <INPUT TYPE="SUBMIT" VALUE="Zero Statistics"> </FORM> <P> <FORM METHOD="POST" ACTION="/~cycle-acc "> <INPUT TYPE="SUBMIT" VALUE="Cycle Access Log"> </FORM> <P> <FORM METHOD="POST" ACTION="/~cycle-err"> <INPUT TYPE="SUBMIT" VALUE="Cycle Error Log"> </FORM> <P> <FORM METHOD="POST" ACTION="/~cycle-both"> <INPUT TYPE="SUBMIT" VALUE="Cycle Both Logs"> </FORM> If you cycled either of the logfiles, take a look in the <code>logs</code> directory. You should see the cycled-out files with extensions like <code>.001</code>. <HR> That's it for the demo. If you got this far without problems, you have also done a fairly thorough checkout of your server setup. 
